/*
 * Copyright (C) 2010 TopCoder Inc., All Rights Reserved.
 */
package com.hercules.android.receiver.commands;

import org.json.JSONObject;

import com.hercules.android.receiver.Receiver;
import com.hercules.android.receiver.ReceiverUtil;

/**
 * <p>
 * This class is the base class of all command handlers.
 * </p>
 * 
 * @author TCSASSEMBER
 * @version 1.0
 */
public abstract class XRECommandHandler {
    /**
     * Represents the <code>Receiver</code> instance.
     */
    protected Receiver receiver;

    /**
     * Constructor with a <code>Receiver</code> arguments.
     * 
     * @param receiver
     *            the <code>Receiver</code> instance.
     * @throws IllegalArgumentException
     *             if receiver if null
     */
    public XRECommandHandler(Receiver receiver) {
        ReceiverUtil.checkNull("receiver", receiver);

        this.receiver = receiver;
    }

    /**
     * This method will be called before processing the command message.
     * 
     * @param message
     *            the command message to be processed.
     * @throws XRECommandHandlerException
     *             if any error occurs
     */
    protected void preProcessCommand(JSONObject message) throws XRECommandHandlerException {
    }

    /**
     * This method will be called after processing the command message.
     * 
     * @param message
     *            the command message to be processed.
     * @throws XRECommandHandlerException
     *             if any error occurs
     */
    protected void postProcessCommand(JSONObject message) throws XRECommandHandlerException {
    }

    /**
     * This method will be called to process the command message.
     * 
     * @param message
     *            the command message to be processed.
     * @throws XRECommandHandlerException
     *             if any error occurs
     */
    public abstract void processCommand(JSONObject message) throws XRECommandHandlerException;

    /**
     * This method will return a flag indicates whether the canvas need to be
     * updated after the command message was processed.
     * 
     * @param object
     *            the command message.
     * @return true if the canvas need to be updated after the command message
     *         was processed, false otherwise
     */
    public boolean needRedraw(JSONObject object) {
        return true;
    }

    /**
     * This method was called to handle a command message.
     * 
     * @param message
     *            the command message
     * @throws IllegalArgumentException
     *             if message is null
     * @throws XRECommandHandlerException
     *             if any other error occurs
     */
    public void onCommandMessage(JSONObject message) throws XRECommandHandlerException {
        ReceiverUtil.checkNull("message", message);

        synchronized (receiver.getApplicationData().getDataLockObject()) {
            preProcessCommand(message);
            processCommand(message);
            postProcessCommand(message);
        }
    }
}
